/**
 * @file json_utils.c
 * @brief 通用JSON工具函数实现
 * @details 提供基于cJSON库的通用JSON数据处理工具函数实现，包括JSON对象的
 *          创建、解析、操作等功能。适用于各种数据类型的JSON序列化和反序列化。
 * 
 * @author zyb
 * @date 2025-09-27
 * @version 1.0
 * 
 * @note 本文件依赖cJSON库，需要先运行环境配置脚本
 * @see json_utils.h
 * @see cJSON.h
 */

#include "json_utils.h"
#include "logger.h"
#include "cJSON.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

// 定义模块名称
#define LOG_MODULE_NAME "JSON_UTILS"

// 全局错误信息
static char g_error_message[256] = {0};

/* ==================== 函数实现 ==================== */

/**
 * @brief 初始化JSON工具
 * @details 初始化JSON工具模块
 * 
 * @return 初始化结果
 *         - 0: 初始化成功
 *         - 非0: 初始化失败
 */
int json_utils_init(void) {
    LOG_DEBUG(LOG_MODULE_NAME, "初始化JSON工具模块");
    
    // 清空错误信息
    memset(g_error_message, 0, sizeof(g_error_message));
    
    LOG_INFO(LOG_MODULE_NAME, "JSON工具模块初始化完成");
    return 0;
}

/**
 * @brief 销毁JSON工具
 * @details 清理JSON工具资源
 */
void json_utils_destroy(void) {
    LOG_DEBUG(LOG_MODULE_NAME, "销毁JSON工具模块");
    
    // 清空错误信息
    memset(g_error_message, 0, sizeof(g_error_message));
    
    LOG_INFO(LOG_MODULE_NAME, "JSON工具模块销毁完成");
}

/* ==================== JSON对象创建 ==================== */

/**
 * @brief 创建JSON对象
 * @details 创建一个新的JSON对象
 * 
 * @return JSON对象指针，失败返回NULL
 */
void* json_utils_create_object(void) {
    LOG_DEBUG(LOG_MODULE_NAME, "创建JSON对象");
    
    void *obj = cJSON_CreateObject();
    if (obj) {
        LOG_DEBUG(LOG_MODULE_NAME, "JSON对象创建成功");
    } else {
        LOG_ERROR(LOG_MODULE_NAME, "JSON对象创建失败");
    }
    
    return obj;
}

/**
 * @brief 创建JSON数组
 * @details 创建一个新的JSON数组
 * 
 * @return JSON数组指针，失败返回NULL
 */
void* json_utils_create_array(void) {
    LOG_DEBUG(LOG_MODULE_NAME, "创建JSON数组");
    
    void *arr = cJSON_CreateArray();
    if (arr) {
        LOG_DEBUG(LOG_MODULE_NAME, "JSON数组创建成功");
    } else {
        LOG_ERROR(LOG_MODULE_NAME, "JSON数组创建失败");
    }
    
    return arr;
}

/**
 * @brief 创建JSON字符串
 * @details 创建一个JSON字符串值
 * 
 * @param string 字符串内容
 * @return JSON字符串指针，失败返回NULL
 */
void* json_utils_create_string(const char *string) {
    LOG_DEBUG(LOG_MODULE_NAME, "创建JSON字符串");
    
    if (!string) {
        LOG_ERROR(LOG_MODULE_NAME, "字符串参数为空");
        snprintf(g_error_message, sizeof(g_error_message), "字符串参数为空");
        return NULL;
    }
    
    void *str = cJSON_CreateString(string);
    if (str) {
        LOG_DEBUG(LOG_MODULE_NAME, "JSON字符串创建成功: %s", string);
    } else {
        LOG_ERROR(LOG_MODULE_NAME, "JSON字符串创建失败");
    }
    
    return str;
}

/**
 * @brief 创建JSON数字
 * @details 创建一个JSON数字值
 * 
 * @param number 数字值
 * @return JSON数字指针，失败返回NULL
 */
void* json_utils_create_number(double number) {
    LOG_DEBUG(LOG_MODULE_NAME, "创建JSON数字: %f", number);
    
    void *num = cJSON_CreateNumber(number);
    if (num) {
        LOG_DEBUG(LOG_MODULE_NAME, "JSON数字创建成功");
    } else {
        LOG_ERROR(LOG_MODULE_NAME, "JSON数字创建失败");
    }
    
    return num;
}

/**
 * @brief 创建JSON布尔值
 * @details 创建一个JSON布尔值
 * 
 * @param boolean 布尔值
 * @return JSON布尔指针，失败返回NULL
 */
void* json_utils_create_bool(bool boolean) {
    LOG_DEBUG(LOG_MODULE_NAME, "创建JSON布尔值: %s", boolean ? "true" : "false");
    
    void *bool_val = cJSON_CreateBool(boolean ? 1 : 0);
    if (bool_val) {
        LOG_DEBUG(LOG_MODULE_NAME, "JSON布尔值创建成功");
    } else {
        LOG_ERROR(LOG_MODULE_NAME, "JSON布尔值创建失败");
    }
    
    return bool_val;
}

/* ==================== JSON对象操作 ==================== */

/**
 * @brief 添加字符串到JSON对象
 * @details 向JSON对象添加字符串字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param string 字符串值
 * @return 操作结果
 */
json_result_t json_utils_add_string_to_object(void *object, const char *name, const char *string) {
    LOG_DEBUG(LOG_MODULE_NAME, "添加字符串字段到JSON对象: %s = %s", name, string ? string : "NULL");
    
    if (!object || !name) {
        LOG_ERROR(LOG_MODULE_NAME, "对象或字段名为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象或字段名为空");
        return JSON_RESULT_INVALID_PARAM;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *json_string = cJSON_CreateString(string);
    if (!json_string) {
        LOG_ERROR(LOG_MODULE_NAME, "创建JSON字符串失败");
        snprintf(g_error_message, sizeof(g_error_message), "创建JSON字符串失败");
        return JSON_RESULT_MEMORY_ERROR;
    }
    
    cJSON_AddItemToObject(json_object, name, json_string);
    LOG_DEBUG(LOG_MODULE_NAME, "字符串字段添加成功");
    return JSON_RESULT_SUCCESS;
}

/**
 * @brief 添加数字到JSON对象
 * @details 向JSON对象添加数字字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param number 数字值
 * @return 操作结果
 */
json_result_t json_utils_add_number_to_object(void *object, const char *name, double number) {
    LOG_DEBUG(LOG_MODULE_NAME, "添加数字字段到JSON对象: %s = %f", name, number);
    
    if (!object || !name) {
        LOG_ERROR(LOG_MODULE_NAME, "对象或字段名为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象或字段名为空");
        return JSON_RESULT_INVALID_PARAM;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *json_number = cJSON_CreateNumber(number);
    if (!json_number) {
        LOG_ERROR(LOG_MODULE_NAME, "创建JSON数字失败");
        snprintf(g_error_message, sizeof(g_error_message), "创建JSON数字失败");
        return JSON_RESULT_MEMORY_ERROR;
    }
    
    cJSON_AddItemToObject(json_object, name, json_number);
    LOG_DEBUG(LOG_MODULE_NAME, "数字字段添加成功");
    return JSON_RESULT_SUCCESS;
}

/**
 * @brief 添加布尔值到JSON对象
 * @details 向JSON对象添加布尔字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param boolean 布尔值
 * @return 操作结果
 */
json_result_t json_utils_add_bool_to_object(void *object, const char *name, bool boolean) {
    LOG_DEBUG(LOG_MODULE_NAME, "添加布尔字段到JSON对象: %s = %s", name, boolean ? "true" : "false");
    
    if (!object || !name) {
        LOG_ERROR(LOG_MODULE_NAME, "对象或字段名为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象或字段名为空");
        return JSON_RESULT_INVALID_PARAM;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *json_bool = cJSON_CreateBool(boolean ? 1 : 0);
    if (!json_bool) {
        LOG_ERROR(LOG_MODULE_NAME, "创建JSON布尔值失败");
        snprintf(g_error_message, sizeof(g_error_message), "创建JSON布尔值失败");
        return JSON_RESULT_MEMORY_ERROR;
    }
    
    cJSON_AddItemToObject(json_object, name, json_bool);
    LOG_DEBUG(LOG_MODULE_NAME, "布尔字段添加成功");
    return JSON_RESULT_SUCCESS;
}

/**
 * @brief 添加对象到JSON对象
 * @details 向JSON对象添加子对象字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param item 子对象
 * @return 操作结果
 */
json_result_t json_utils_add_item_to_object(void *object, const char *name, void *item) {
    LOG_DEBUG(LOG_MODULE_NAME, "添加子对象到JSON对象: %s", name);
    
    if (!object || !name || !item) {
        LOG_ERROR(LOG_MODULE_NAME, "对象、字段名或项目为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象、字段名或项目为空");
        return JSON_RESULT_INVALID_PARAM;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *json_item = (cJSON*)item;
    
    cJSON_AddItemToObject(json_object, name, json_item);
    LOG_DEBUG(LOG_MODULE_NAME, "子对象添加成功");
    return JSON_RESULT_SUCCESS;
}

/**
 * @brief 添加项目到JSON数组
 * @details 向JSON数组添加项目
 * 
 * @param array JSON数组
 * @param item 要添加的项目
 * @return 操作结果
 */
json_result_t json_utils_add_item_to_array(void *array, void *item) {
    LOG_DEBUG(LOG_MODULE_NAME, "添加项目到JSON数组");
    
    if (!array || !item) {
        LOG_ERROR(LOG_MODULE_NAME, "数组或项目为空");
        snprintf(g_error_message, sizeof(g_error_message), "数组或项目为空");
        return JSON_RESULT_INVALID_PARAM;
    }
    
    cJSON *json_array = (cJSON*)array;
    cJSON *json_item = (cJSON*)item;
    
    cJSON_AddItemToArray(json_array, json_item);
    LOG_DEBUG(LOG_MODULE_NAME, "项目添加到数组成功");
    return JSON_RESULT_SUCCESS;
}

/* ==================== JSON对象解析 ==================== */

/**
 * @brief 解析JSON字符串
 * @details 将JSON字符串解析为JSON对象
 * 
 * @param json_string JSON字符串
 * @return JSON对象指针，失败返回NULL
 */
void* json_utils_parse(const char *json_string) {
    LOG_DEBUG(LOG_MODULE_NAME, "解析JSON字符串");
    
    if (!json_string) {
        LOG_ERROR(LOG_MODULE_NAME, "JSON字符串为空");
        snprintf(g_error_message, sizeof(g_error_message), "JSON字符串为空");
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "JSON字符串内容: %s", json_string);
    
    cJSON *json = cJSON_Parse(json_string);
    if (!json) {
        const char *error_ptr = cJSON_GetErrorPtr();
        if (error_ptr) {
            LOG_ERROR(LOG_MODULE_NAME, "JSON解析错误: %s", error_ptr);
            snprintf(g_error_message, sizeof(g_error_message), "JSON解析错误: %s", error_ptr);
        } else {
            LOG_ERROR(LOG_MODULE_NAME, "JSON解析失败");
            snprintf(g_error_message, sizeof(g_error_message), "JSON解析失败");
        }
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "JSON解析成功");
    return json;
}

/**
 * @brief 获取JSON对象中的字符串
 * @details 从JSON对象中获取字符串字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @return 字符串指针，失败返回NULL
 */
const char* json_utils_get_string(void *object, const char *name) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取JSON对象中的字符串字段: %s", name);
    
    if (!object || !name) {
        LOG_ERROR(LOG_MODULE_NAME, "对象或字段名为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象或字段名为空");
        return NULL;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *item = cJSON_GetObjectItem(json_object, name);
    
    if (!item) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不存在", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不存在", name);
        return NULL;
    }
    
    if (!cJSON_IsString(item)) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不是字符串类型", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不是字符串类型", name);
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取字符串字段成功: %s = %s", name, item->valuestring);
    return item->valuestring;
}

/**
 * @brief 获取JSON对象中的数字
 * @details 从JSON对象中获取数字字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param number 输出数字值
 * @return 操作结果
 */
json_result_t json_utils_get_number(void *object, const char *name, double *number) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取JSON对象中的数字字段: %s", name);
    
    if (!object || !name || !number) {
        LOG_ERROR(LOG_MODULE_NAME, "对象、字段名或输出参数为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象、字段名或输出参数为空");
        return JSON_RESULT_INVALID_PARAM;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *item = cJSON_GetObjectItem(json_object, name);
    
    if (!item) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不存在", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不存在", name);
        return JSON_RESULT_NOT_FOUND;
    }
    
    if (!cJSON_IsNumber(item)) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不是数字类型", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不是数字类型", name);
        return JSON_RESULT_TYPE_ERROR;
    }
    
    *number = item->valuedouble;
    LOG_DEBUG(LOG_MODULE_NAME, "获取数字字段成功: %s = %f", name, *number);
    return JSON_RESULT_SUCCESS;
}

/**
 * @brief 获取JSON对象中的布尔值
 * @details 从JSON对象中获取布尔字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @param boolean 输出布尔值
 * @return 操作结果
 */
json_result_t json_utils_get_bool(void *object, const char *name, bool *boolean) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取JSON对象中的布尔字段: %s", name);
    
    if (!object || !name || !boolean) {
        LOG_ERROR(LOG_MODULE_NAME, "对象、字段名或输出参数为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象、字段名或输出参数为空");
        return JSON_RESULT_INVALID_PARAM;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *item = cJSON_GetObjectItem(json_object, name);
    
    if (!item) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不存在", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不存在", name);
        return JSON_RESULT_NOT_FOUND;
    }
    
    if (!cJSON_IsBool(item)) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不是布尔类型", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不是布尔类型", name);
        return JSON_RESULT_TYPE_ERROR;
    }
    
    *boolean = cJSON_IsTrue(item);
    LOG_DEBUG(LOG_MODULE_NAME, "获取布尔字段成功: %s = %s", name, *boolean ? "true" : "false");
    return JSON_RESULT_SUCCESS;
}

/**
 * @brief 获取JSON对象中的子对象
 * @details 从JSON对象中获取子对象字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @return 子对象指针，失败返回NULL
 */
void* json_utils_get_object(void *object, const char *name) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取JSON对象中的子对象字段: %s", name);
    
    if (!object || !name) {
        LOG_ERROR(LOG_MODULE_NAME, "对象或字段名为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象或字段名为空");
        return NULL;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *item = cJSON_GetObjectItem(json_object, name);
    
    if (!item) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不存在", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不存在", name);
        return NULL;
    }
    
    if (!cJSON_IsObject(item)) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不是对象类型", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不是对象类型", name);
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取子对象字段成功: %s", name);
    return item;
}

/**
 * @brief 获取JSON对象中的数组
 * @details 从JSON对象中获取数组字段
 * 
 * @param object JSON对象
 * @param name 字段名
 * @return 数组指针，失败返回NULL
 */
void* json_utils_get_array(void *object, const char *name) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取JSON对象中的数组字段: %s", name);
    
    if (!object || !name) {
        LOG_ERROR(LOG_MODULE_NAME, "对象或字段名为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象或字段名为空");
        return NULL;
    }
    
    cJSON *json_object = (cJSON*)object;
    cJSON *item = cJSON_GetObjectItem(json_object, name);
    
    if (!item) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不存在", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不存在", name);
        return NULL;
    }
    
    if (!cJSON_IsArray(item)) {
        LOG_ERROR(LOG_MODULE_NAME, "字段 '%s' 不是数组类型", name);
        snprintf(g_error_message, sizeof(g_error_message), "字段 '%s' 不是数组类型", name);
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取数组字段成功: %s", name);
    return item;
}

/**
 * @brief 获取数组大小
 * @details 获取JSON数组的大小
 * 
 * @param array JSON数组
 * @return 数组大小，失败返回-1
 */
int json_utils_get_array_size(void *array) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取JSON数组大小");
    
    if (!array) {
        LOG_ERROR(LOG_MODULE_NAME, "数组为空");
        snprintf(g_error_message, sizeof(g_error_message), "数组为空");
        return -1;
    }
    
    cJSON *json_array = (cJSON*)array;
    if (!cJSON_IsArray(json_array)) {
        LOG_ERROR(LOG_MODULE_NAME, "不是数组类型");
        snprintf(g_error_message, sizeof(g_error_message), "不是数组类型");
        return -1;
    }
    
    int size = cJSON_GetArraySize(json_array);
    LOG_DEBUG(LOG_MODULE_NAME, "获取数组大小成功: %d", size);
    return size;
}

/**
 * @brief 获取数组中的项目
 * @details 从JSON数组中获取指定索引的项目
 * 
 * @param array JSON数组
 * @param index 索引
 * @return 项目指针，失败返回NULL
 */
void* json_utils_get_array_item(void *array, int index) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取JSON数组中的项目: 索引=%d", index);
    
    if (!array) {
        LOG_ERROR(LOG_MODULE_NAME, "数组为空");
        snprintf(g_error_message, sizeof(g_error_message), "数组为空");
        return NULL;
    }
    
    cJSON *json_array = (cJSON*)array;
    if (!cJSON_IsArray(json_array)) {
        LOG_ERROR(LOG_MODULE_NAME, "不是数组类型");
        snprintf(g_error_message, sizeof(g_error_message), "不是数组类型");
        return NULL;
    }
    
    cJSON *item = cJSON_GetArrayItem(json_array, index);
    if (!item) {
        LOG_ERROR(LOG_MODULE_NAME, "索引 %d 超出范围", index);
        snprintf(g_error_message, sizeof(g_error_message), "索引 %d 超出范围", index);
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取数组项目成功: 索引=%d", index);
    return item;
}

/* ==================== JSON序列化 ==================== */

/**
 * @brief 将JSON对象转换为字符串
 * @details 将JSON对象序列化为格式化的字符串
 * 
 * @param object JSON对象
 * @return JSON字符串，需要调用者释放内存
 */
char* json_utils_print(void *object) {
    LOG_DEBUG(LOG_MODULE_NAME, "将JSON对象序列化为格式化字符串");
    
    if (!object) {
        LOG_ERROR(LOG_MODULE_NAME, "对象为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象为空");
        return NULL;
    }
    
    cJSON *json_object = (cJSON*)object;
    char *json_string = cJSON_Print(json_object);
    
    if (!json_string) {
        LOG_ERROR(LOG_MODULE_NAME, "JSON序列化失败");
        snprintf(g_error_message, sizeof(g_error_message), "JSON序列化失败");
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "JSON序列化成功，长度: %zu", strlen(json_string));
    return json_string;
}

/**
 * @brief 将JSON对象转换为紧凑字符串
 * @details 将JSON对象序列化为紧凑的字符串（无格式化）
 * 
 * @param object JSON对象
 * @return JSON字符串，需要调用者释放内存
 */
char* json_utils_print_unformatted(void *object) {
    LOG_DEBUG(LOG_MODULE_NAME, "将JSON对象序列化为紧凑字符串");
    
    if (!object) {
        LOG_ERROR(LOG_MODULE_NAME, "对象为空");
        snprintf(g_error_message, sizeof(g_error_message), "对象为空");
        return NULL;
    }
    
    cJSON *json_object = (cJSON*)object;
    char *json_string = cJSON_PrintUnformatted(json_object);
    
    if (!json_string) {
        LOG_ERROR(LOG_MODULE_NAME, "JSON序列化失败");
        snprintf(g_error_message, sizeof(g_error_message), "JSON序列化失败");
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "JSON紧凑序列化成功，长度: %zu", strlen(json_string));
    return json_string;
}

/* ==================== 内存管理 ==================== */

/**
 * @brief 删除JSON对象
 * @details 释放JSON对象占用的内存
 * 
 * @param object JSON对象
 */
void json_utils_delete(void *object) {
    if (object) {
        LOG_DEBUG(LOG_MODULE_NAME, "删除JSON对象");
        cJSON_Delete((cJSON*)object);
        LOG_DEBUG(LOG_MODULE_NAME, "JSON对象删除完成");
    } else {
        LOG_DEBUG(LOG_MODULE_NAME, "JSON对象为空，无需删除");
    }
}

/**
 * @brief 释放JSON字符串
 * @details 释放由json_utils_print分配的内存
 * 
 * @param json_string JSON字符串
 */
void json_utils_free_string(char *json_string) {
    if (json_string) {
        LOG_DEBUG(LOG_MODULE_NAME, "释放JSON字符串内存");
        free(json_string);
        LOG_DEBUG(LOG_MODULE_NAME, "JSON字符串内存释放完成");
    } else {
        LOG_DEBUG(LOG_MODULE_NAME, "JSON字符串为空，无需释放");
    }
}

/* ==================== 工具函数 ==================== */

/**
 * @brief 检查JSON对象是否有效
 * @details 检查JSON对象是否为有效对象
 * 
 * @param object JSON对象
 * @return true: 有效, false: 无效
 */
bool json_utils_is_valid(void *object) {
    bool valid = object != NULL;
    LOG_DEBUG(LOG_MODULE_NAME, "检查JSON对象有效性: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 检查JSON对象是否为指定类型
 * @details 检查JSON对象的类型
 * 
 * @param object JSON对象
 * @param type_name 类型名称 ("object", "array", "string", "number", "boolean")
 * @return true: 匹配, false: 不匹配
 */
bool json_utils_is_type(void *object, const char *type_name) {
    LOG_DEBUG(LOG_MODULE_NAME, "检查JSON对象类型: %s", type_name ? type_name : "NULL");
    
    if (!object || !type_name) {
        LOG_DEBUG(LOG_MODULE_NAME, "对象或类型名为空");
        return false;
    }
    
    cJSON *json_object = (cJSON*)object;
    bool is_type = false;
    
    if (strcmp(type_name, "object") == 0) {
        is_type = cJSON_IsObject(json_object);
    } else if (strcmp(type_name, "array") == 0) {
        is_type = cJSON_IsArray(json_object);
    } else if (strcmp(type_name, "string") == 0) {
        is_type = cJSON_IsString(json_object);
    } else if (strcmp(type_name, "number") == 0) {
        is_type = cJSON_IsNumber(json_object);
    } else if (strcmp(type_name, "boolean") == 0) {
        is_type = cJSON_IsBool(json_object);
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "类型检查结果: %s", is_type ? "匹配" : "不匹配");
    return is_type;
}

/**
 * @brief 获取JSON错误信息
 * @details 获取最后一次JSON操作的错误信息
 * 
 * @return 错误信息字符串
 */
const char* json_utils_get_error(void) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取JSON错误信息: %s", g_error_message);
    return g_error_message;
}
